home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Extras / BOOPSI / GI1 / Doc / button_gc.doc < prev    next >
Encoding:
Text File  |  1994-03-11  |  16.1 KB  |  405 lines
  1. TABLE OF CONTENTS
  2.  
  3. button.gadget/--datasheet--
  4. button.gadget/GM_GOACTIVE
  5. button.gadget/GM_GOINACTIVE
  6. button.gadget/GM_HANDLEINPUT
  7. button.gadget/GM_HITTEST
  8. button.gadget/GM_LAYOUT
  9. button.gadget/GM_RENDER
  10. button.gadget/OM_NEW
  11. button.gadget/OM_SET
  12. button.gadget/--datasheet--                       button.gadget/--datasheet--
  13.  
  14.      NAME
  15.         button.gadget--Action button                            (V42)
  16.  
  17.      SUPERCLASS
  18.         gadgetclass
  19.  
  20.      DESCRIPTION
  21.         The button gadget class is used to create action buttons that are
  22.         momentary, toggle and sticky.  This class also supports relativity
  23.         and placement within the window border.
  24.  
  25.         An advantage that this class provides that the system buttongclass
  26.         doesn't support fully is:
  27.  
  28.          o Centered images.
  29.  
  30.          o Centered pen-sensitive glyphs.
  31.  
  32.          o Ability to change the text and background colors for normal
  33.            and selected buttons.
  34.  
  35.      METHODS
  36.         OM_NEW--Create the button gadget.  Passed to superclass, then OM_SET.
  37.  
  38.         OM_SET--Set object attributes.  Passed to superclass first.
  39.  
  40.         OM_UPDATE--Set object notification attributes.  Passed to superclass
  41.             first.
  42.  
  43.         GM_LAYOUT--Calculate gadget imagry positioning.  Passed to superclass
  44.             first.
  45.  
  46.         GM_RENDER--Renders the gadget imagry.  Overrides the superclass.
  47.  
  48.         GM_HITTEST--Determines if mouse is within the gadget rectangle.  Over-
  49.             rides the superclass.
  50.  
  51.         GM_GOACTIVE--Handles activation, toggle-select and button-select.
  52.             Overrides the superclass.
  53.  
  54.         GM_HANDLEINPUT--Handles input events once active.  Handles cycle
  55.             buttons, repeat and RMB abort.  Overrides the superclass.
  56.  
  57.         GM_GOINACTIVE--Deselects the button.  Overrides the superclass.
  58.  
  59.         All other methods are passed to the superclass, including OM_DISPOSE.
  60.  
  61.      ATTRIBUTES
  62.         GA_ToggleSelect (BOOL) -- Indicate that the gadget is a toggle button.
  63.             Defaults to FALSE.
  64.  
  65.         GA_Selected (BOOL) -- Determines whether the button is selected or
  66.             not.  Changing selection state will invoke GM_RENDER.  Setting
  67.             selected causes BUTTON_Current to go to 1.  Clearing selected
  68.             causes BUTTON_Current to go to 0.  Defaults to FALSE.
  69.  
  70.         GA_Disabled (BOOL) -- Determines whether the button is disabled or
  71.             not.  Changing disable state will invoke GM_RENDER.  A disabled
  72.             button's border and label are all rendered in SHADOWPEN and then
  73.             dusted in a ghosting pattern that is rendered in SHADOWPEN.
  74.             Defaults to FALSE.
  75.  
  76.         GA_Text (STRPTR) -- Used to specify the NULL terminated string to use
  77.             as the text for the gadget.  The Text() function is used to draw
  78.             the text.  The class does not currently support underlining of
  79.             the keyboard shortcut character.  NULL is valid input.  Changing
  80.             the label will invoke GM_LAYOUT and then GM_RENDER.
  81.  
  82.         GA_Image (struct Image *) -- Used to specify the image to use for the
  83.             label of the gadget.  The DrawImage() function is used to draw
  84.             the image.  NULL is valid input.  Changing the label will invoke
  85.             GM_LAYOUT and then GM_RENDER.
  86.  
  87.         GA_TextAttr (struct TextAttr *) -- Text attribute for the font to
  88.             use for the labels.
  89.  
  90.         GA_ReadOnly (BOOL) -- Read-only gadgets ignore activation attempts.
  91.             Defaults to FALSE.
  92.  
  93.         BUTTON_Glyph (struct Image *) -- Used to specify the image to use for
  94.             the label of the gadget.  The BltTemplate() function is used to
  95.             draw each plane of the image.  NULL is valid input.  Changing the
  96.             label will invoke GM_LAYOUT and then GM_RENDER.
  97.  
  98.         BUTTON_PushButton (BOOL) -- Used to indicate that the button stays
  99.             pressed in when the user selects it with the mouse.  The button
  100.             may programmatically be deselected using {GA_Selected, FALSE}.
  101.             Defaults to FALSE.
  102.  
  103.         BUTTON_Array (LONG) -- Indicates that the label is an array, and
  104.             indicates the number of elements in the array.  This allows the
  105.             gadget to be used as a checkbox or a cycle gadget without the
  106.             cycle glyph.  Defaults to 1.
  107.  
  108.         BUTTON_Current (LONG) -- Used to select the current image from the
  109.             BUTTON_Array.  Changing the current image will invoke GM_LAYOUT
  110.             and then GM_RENDER.  Defaults to zero.
  111.  
  112.         BUTTON_TextPen (LONG) -- Indicate the pen number used to render the
  113.             IDS_NORMAL text.  If -1 is specified, then TEXTPEN is used.
  114.             Defaults to -1.
  115.  
  116.         BUTTON_BackgroundPen (LONG) -- Indicate the pen number used to render
  117.             the IDS_NORMAL background.  If -1 is specified, then BACKGROUNDPEN
  118.             is used.  Defaults to -1.
  119.  
  120.         BUTTON_FillTextPen (LONG) -- Indicate the pen number used to render
  121.             the IDS_SELECTED text.  If -1 is specified, then FILLTEXTPEN is
  122.             used.  Defaults to -1.
  123.  
  124.         BUTTON_FillPen (LONG) -- Indicate the pen number used to render the
  125.             IDS_SELECTED background.  If -1 is specified, then FILLPEN is used
  126.         .
  127.             Defaults to -1.
  128.  
  129. button.gadget/GM_GOACTIVE                           button.gadget/GM_GOACTIVE
  130.  
  131.      NAME
  132.         GM_GOACTIVE--Activate a gadget.                         (V42)
  133.  
  134.      FUNCTION
  135.         The GM_GOACTIVE method is used to indicate to a gadget that it has
  136.         become active.  This method overrides the superclass.
  137.  
  138.         GA_ToggleSelect:  Toggles selection state.
  139.  
  140.         BUTTON_PushButton:  If not selected, then becomes selected and sets
  141.             BUTTON_Current to 1.  If selected and BUTTON_Array is greater than
  142.             one, then will cycle through the array, while staying selected,
  143.             with 1 being the lower bounds.
  144.  
  145.         BUTTON_Array: Sets selection state and cycle through the array with 0
  146.             being the lower bounds.
  147.  
  148.         Otherwise: Sets selection state.
  149.  
  150.         Invokes GM_RENDER with GREDRAW_REDRAW set.
  151.  
  152.      RESULT
  153.         For GA_ToggleSelect returns GMR_VERIFY | GMR_NOREUSE.
  154.  
  155.         For BUTTON_PushButton returns GMR_VERIFY | GMR_NOREUSE when the
  156.         state changes, otherwise returns GMR_NOREUSE.
  157.  
  158.         All other cases returns GMR_MEACTIVE.
  159.  
  160.         Sets the *msg->gpi_Termination field to BUTTON_Current, which in turn
  161.         fills in the IntuiMessage->Code field.
  162.  
  163. button.gadget/GM_GOINACTIVE                       button.gadget/GM_GOINACTIVE
  164.  
  165.      NAME
  166.         GM_GOINACTIVE--Button has lost activation.              (V42)
  167.  
  168.      FUNCTION
  169.         The GM_GOINACTIVE method is used to indicate that the button has
  170.         become inactive.  This method overrides the superclass.
  171.  
  172.         For momentary buttons, this will cause the GFLG_SELECTED flag to be
  173.         cleared and the GM_RENDER method to be called with GREDRAW_REDRAW.
  174.  
  175.      RESULT
  176.         This method returns 0.
  177.  
  178. button.gadget/GM_HANDLEINPUT                     button.gadget/GM_HANDLEINPUT
  179.  
  180.      NAME
  181.         GM_HANDLEINPUT--Handle input events.                    (V42)
  182.  
  183.      FUNCTION
  184.         The GM_HANDLEINPUT method is used to handle the input events of an
  185.         active button gadget.  This method overrides the superclass.
  186.  
  187.         This method correctly handles RMB abort.
  188.  
  189.      RESULT
  190.         This method returns GMR_MEACTIVE as long as the gadget is active.
  191.  
  192. button.gadget/GM_HITTEST                             button.gadget/GM_HITTEST
  193.  
  194.      NAME
  195.         GM_HITTEST--Is gadget hit.                              (V42)
  196.  
  197.      FUNCTION
  198.         The GM_HITTEST method is used to determine if the given mouse
  199.         coordinates are within the domain of the button.  This method
  200.         overrides the superclass.
  201.  
  202.      RESULT
  203.         This method returns GMR_GADGETHIT if within the domain, otherwise
  204.         zero is returned.
  205.  
  206.         If the gadget is GA_ReadOnly, then zero is always returned.
  207.  
  208. button.gadget/GM_LAYOUT                               button.gadget/GM_LAYOUT
  209.  
  210.      NAME
  211.         GM_LAYOUT--Calculate the positioning of the imagry.     (V42)
  212.  
  213.      FUNCTION
  214.         The GM_LAYOUT method is used to calculate the domain of the button
  215.         and to center the label within the domain.  This method is passed to
  216.         the superclass first.
  217.  
  218.         Gadget relativity is fully supported.
  219.  
  220.      RESULT
  221.         This method returns 0.
  222.  
  223. button.gadget/GM_RENDER                               button.gadget/GM_RENDER
  224.  
  225.      NAME
  226.         GM_RENDER--Render the visuals of the button.            (V42)
  227.  
  228.      FUNCTION
  229.         The GM_RENDER method is used to render the visuals of the button.
  230.         This method overrides the superclass.
  231.  
  232.         The border of the gadget is drawn first.  Disabled gadgets get a
  233.         border that is drawn completely in SHADOWPEN.  A selected or
  234.         read-only button gets SHADOWPEN for the left and top sides, and
  235.         SHINEPEN for the right and bottom sides.  A normal button gets
  236.         SHINEPEN for the left and top sides, and SHADOWPEN for the
  237.         right and bottom sides.
  238.  
  239.         The inside of the button is then drawn.  A normal button gets
  240.         filled with BUTTON_BackgroundPen.  A selected button gets filled
  241.         with BUTTON_FillPen.
  242.  
  243.         Then the label is drawn.
  244.  
  245.             GA_Text:  Text() is used to render the text.  BUTTON_TextPen
  246.             is used for a normal button and BUTTON_FillTextPen is used for a
  247.             selected button.
  248.  
  249.             GA_Image:  DrawImageState() is used to render the image.  Note
  250.             that the background pen color is already set appropriately for
  251.             the image state.
  252.  
  253.             BUTTON_Glyph:  BltTemplate() is used to render each of the planes
  254.             of the image.  BUTTON_TextPen is used for a normal button and
  255.             BUTTON_FillTextPen is used for a selected button.  The second
  256.             and higher planes are render using SHADOWPEN.
  257.  
  258.         If the button is disabled, then the ghosting pattern is applied.
  259.  
  260.      RESULT
  261.         This method returns 0.
  262.  
  263. button.gadget/OM_NEW                                     button.gadget/OM_NEW
  264.  
  265.      NAME
  266.         OM_NEW--Create a button.gadget object.                  (V42)
  267.  
  268.      FUNCTION
  269.         The OM_NEW method is used to create an instance of the button.gadget
  270.         class.  This method is passed to the superclass first.
  271.  
  272.      ATTRIBUTES
  273.         The following attributes can be specified at creation time.
  274.  
  275.         GA_ToggleSelect (BOOL) -- Indicate that the gadget is a toggle button.
  276.             Defaults to FALSE.
  277.  
  278.         GA_Selected (BOOL) -- Determines whether the button is selected or
  279.             not.  Defaults to FALSE.
  280.  
  281.         GA_Disabled (BOOL) -- Determines whether the button is disabled or
  282.             not.  Defaults to FALSE.
  283.  
  284.         GA_Text (STRPTR) -- Used to specify the NULL terminated string to use
  285.             as the text for the gadget.
  286.  
  287.         GA_Image (struct Image *) -- Used to specify the image to use for the
  288.             label of the gadget.
  289.  
  290.         GA_TextAttr (struct TextAttr *) -- Text attribute for the font to
  291.             use for the labels.
  292.  
  293.         GA_ReadOnly (BOOL) -- Read-only gadgets ignore activation attempts.
  294.             Defaults to FALSE.
  295.  
  296.         BUTTON_Glyph (struct Image *) -- Used to specify the image to use for
  297.             the label of the gadget.
  298.  
  299.         BUTTON_PushButton (BOOL) -- Used to indicate that the button stays
  300.             pressed in when the user selects it with the mouse.  The button
  301.             may programmatically be deselected using {GA_Selected, FALSE}.
  302.             Defaults to FALSE.
  303.  
  304.         BUTTON_Array (LONG) -- Indicates that the label is an array, and
  305.             indicates the number of elements in the array.  This allows the
  306.             gadget to be used as a checkbox or a cycle gadget without the
  307.             cycle glyph.  Defaults to 1.
  308.  
  309.         BUTTON_Current (LONG) -- Used to select the current image from the
  310.             BUTTON_Array.  Defaults to zero.
  311.  
  312.         BUTTON_TextPen (LONG) -- Indicate the pen number used to render the
  313.             IDS_NORMAL text.  If -1 is specified, then TEXTPEN is used.
  314.             Defaults to -1.
  315.  
  316.         BUTTON_BackgroundPen (LONG) -- Indicate the pen number used to render
  317.             the IDS_NORMAL background.  If -1 is specified, then BACKGROUNDPEN
  318.             is used.  Defaults to -1.
  319.  
  320.         BUTTON_FillTextPen (LONG) -- Indicate the pen number used to render
  321.             the IDS_SELECTED text.  If -1 is specified, then FILLTEXTPEN is
  322.             used.  Defaults to -1.
  323.  
  324.         BUTTON_FillPen (LONG) -- Indicate the pen number used to render the
  325.             IDS_SELECTED background.  If -1 is specified, then FILLPEN is used
  326.         .
  327.             Defaults to -1.
  328.  
  329.      RESULT
  330.         If the object was created then a pointer to the object is returned,
  331.         otherwise NULL is returned.
  332.  
  333. button.gadget/OM_SET                                     button.gadget/OM_SET
  334.  
  335.      NAME
  336.         OM_SET--Set the attributes of a button.gadget object.   (V42)
  337.  
  338.      FUNCTION
  339.         The OM_SET method is used to set the attributes of a button.gadget.
  340.         This method is passed to the superclass first.
  341.  
  342.      ATTRIBUTES
  343.         The following attributes can be changed at OM_SET or OM_UPDATE.
  344.  
  345.         GA_Selected (BOOL) -- Determines whether the button is selected or
  346.             not.  Changing selection state will invoke GM_RENDER.  Setting
  347.             selected causes BUTTON_Current to go to 1.  Clearing selected
  348.             causes BUTTON_Current to go to 0.  Defaults to FALSE.
  349.  
  350.         GA_Disabled (BOOL) -- Determines whether the button is disabled or
  351.             not.  Changing disable state will invoke GM_RENDER.  A disabled
  352.             button's border and label are all rendered in SHADOWPEN and then
  353.             dusted in a ghosting pattern that is rendered in SHADOWPEN.
  354.             Defaults to FALSE.
  355.  
  356.         GA_Text (STRPTR) -- Used to specify the NULL terminated string to use
  357.             as the text for the gadget.  The Text() function is used to draw
  358.             the text.  The class does not currently support underlining of
  359.             the keyboard shortcut character.  NULL is valid input.  Changing
  360.             the label will invoke GM_LAYOUT and then GM_RENDER.
  361.  
  362.         GA_Image (struct Image *) -- Used to specify the image to use for the
  363.             label of the gadget.  The DrawImage() function is used to draw
  364.             the image.  NULL is valid input.  Changing the label will invoke
  365.             GM_LAYOUT and then GM_RENDER.
  366.  
  367.         GA_TextAttr (struct TextAttr *) -- Text attribute for the font to
  368.             use for the labels.
  369.  
  370.         GA_ReadOnly (BOOL) -- Read-only gadgets ignore activation attempts.
  371.             Defaults to FALSE.
  372.  
  373.         BUTTON_Glyph (struct Image *) -- Used to specify the image to use for
  374.             the label of the gadget.  The BltTemplate() function is used to
  375.             draw each plane of the image.  NULL is valid input.  Changing the
  376.             label will invoke GM_LAYOUT and then GM_RENDER.
  377.  
  378.         BUTTON_Current (LONG) -- Used to select the current image from the
  379.             BUTTON_Array.  Changing the current image will invoke GM_LAYOUT
  380.             and then GM_RENDER.  Defaults to zero.
  381.  
  382.         BUTTON_TextPen (LONG) -- Indicate the pen number used to render the
  383.             IDS_NORMAL text.  If -1 is specified, then TEXTPEN is used.
  384.             Defaults to -1.  Changing the pen will invoke GM_RENDER.
  385.  
  386.         BUTTON_BackgroundPen (LONG) -- Indicate the pen number used to render
  387.             the IDS_NORMAL background.  If -1 is specified, then BACKGROUNDPEN
  388.             is used.  Defaults to -1.  Changing the pen will invoke GM_RENDER.
  389.  
  390.         BUTTON_FillTextPen (LONG) -- Indicate the pen number used to render
  391.             the IDS_SELECTED text.  If -1 is specified, then FILLTEXTPEN is
  392.             used.  Defaults to -1.  Changing the pen will invoke GM_RENDER.
  393.  
  394.         BUTTON_FillPen (LONG) -- Indicate the pen number used to render the
  395.             IDS_SELECTED background.  If -1 is specified, then FILLPEN is used
  396.         .
  397.             Defaults to -1.  Changing the pen will invoke GM_RENDER.
  398.  
  399.      RESULT
  400.         The class will update the attributes of object.  Changing some
  401.         attributes will result in GM_LAYOUT and/or GM_RENDER being called.
  402.  
  403.         The return value will be non-zero if the gadget needs to be refreshed.
  404.  
  405.